Skip to main content

Authentication Functions

The Authentication adapter provides functionality to authenticate and manage a user's Epicenter session.

Importing the adapter​

To use the functions of the Authentication adapter, import it as shown:
import { authAdapter } from 'epicenter-libs';

The authAdapter namespace exports functions that make calls to the Authentication API.

learn more

For descriptions of the objects used by the authentication adapter functions, read Authentication entities.

Login​

Removes any previous sessions and returns a new authenticated session.

Function signature
export async function login(
    credentials: UserCredentials | AppCredentials,
    optionals: { objectType?: string, forcePathInclusion?: boolean } & RoutingOptions = {}
): Promise<Session>

Permissions​

Requires a role of ANONYMOUS or higher.

Parameters​

  1. credentials: A union of two possible types of login credentials:

    • UserCredentials: Contains a user’s handle, password, and group key.
    • AppCredentials: Contains an application’s secret key.

  2. optionals: An object containing additional options:

    • objectType (optional, type: string): Specifies the type of object ("user" or "account").
    • forcePathInclusion (optional, type: boolean): Forces an admin login to include the path in the generated cookie. When an admin login should be limited in scope to a single project, this prevents login issues when trying to access other simulations.
    • RoutingOptions: An (object with routing-specific options)[/docs/Developer%20reference/Utils/routers.md#routingoptions-interface]

Return value​

A Promise resolving to the new Session object.

Usage example​

Here is a JavaScript example where the login() function is called to log in a user:

JavaScript example
import authAdapter from 'epicenter-libs';

const usernameEl = document.getElementById('username');
const passwordEl = document.getElementById('password');
const groupEl = document.getElementById('group');
const groupLabelEl = document.getElementById('group-label');
const adminCheckboxEl = document.getElementById('admin');

const session = await authAdapter.login({
    handle: usernameEl.value,
    password: passwordEl.value,
    groupKey: groupEl.value,
}, {objectType: adminCheckboxEl.checked ? 'admin' : 'user' });

Update session​

Update a user's session to the correct group or an admin's session to the correct account.

Function signature
export async function regenerate(
                        groupOrAccount: string,
                        optionals: { objectType?: string, forcePathInclusion?: boolean, } & 
                        RoutingOptions = {}
                        ): Promise<Session>
warning

The function fails if the user/admin does not already belong to the group/account.

Permissions​

Requires a role of ANONYMOUS or higher.

Parameters​

  1. groupOrAccount: Group key or account name

  2. optionals: An object containing additional options:

    • objectType (optional, type: string): "user" or "account". Defaults to "user".
    • forcePathInclusion (optional, type: boolean): Forces an admin login to include the path in the generated cookie. When an admin login should be limited in scope to a single project, this prevents login issues when trying to access other simulations.
    • RoutingOptions: An object with routing-specific options

Return value​

A Promise resolving to the updated Session object.

View current session​

Function signature
export async function getSession(optionals: RoutingOptions): Promise<Session>

Permissions​

Requires a role of ANONYMOUS or higher.

Parameters​

RoutingOptions is an optional parameter containing an object with routing-specific options.

Return value​

A Promise resolving to the currently authenticated Session object.

Local session​

The following three functions facilitate storing the session locally for faster access. No API calls are made.

Get local session​

getLocalSession() returns the local session as a Session object.

JavaScript example
import authAdapter from 'epicenter-libs';
const session = authAdapter.getLocalSession();

Set local session​

setLocalSession(session: Session) updates the local session with the Session object passes in the parameter and returns the Session object.

Remove local session​

removeLocalSession() sets the local session to undefined and disconnects all live connections. Returns Promise<void>.

Logout​

Log out of current Epicenter session:

  • Terminate the user session.
  • Disconnect live WebSockets connections.
  • Removes the user from the presence cache.
learn more

The logout function ensures that the user's presence is dropped immediately when the user logs off.

Function signature
export async function logout(
    verificationOptionals: RoutingOptions = {},
    presenceOptionals: RoutingOptions = verificationOptionals
): Promise<void>

Permissions​

Requires a role of PARTICIPANT or higher.

Parameters​

  • verificationOptionals (optional): An object of type RoutingOptions. Defaults to an empty object if not provided. Used for additional verification options.
  • presenceOptionals (optional): An object of type RoutingOptions. Defaults to the value of verificationOptionals if not provided. Used for additional routing options during the presence group deletion process.

Return value​

A Promise that resolves to void.

Usage example​

Here is a JavaScript example where the logout() function is called to log a user out:

JavaScript example
import authAdapter from 'epicenter-libs';

// Define DOM elements
const displayNameEl = document.getElementById('display-name');
const groupRoleEl = document.getElementById('group-role');
const logoutEl = document.getElementById('logout');

logoutEl.onclick = (e) => {
    e.target.disabled = true;
    authAdapter.logout().then(() => {
        displayNameEl.textContent = 'stranger';
        groupRoleEl.textContent = 'not currently signed in on Epicenter';
        e.target.disabled = false;
    });
};

Reset a user's password​

Send a link to reset a user's password to their email.

Function signature
export async function resetPassword(
                                handle: string,
                                optionals: {  redirectURL?: string, subject?: string,} & 
                                RoutingOptions = {}
                                ): Promise<void>

Permissions​

Requires a role of ANONYMOUS or higher.

Parameters​

  1. handle (type: string): User's handle used to log in

  2. optionals: Optional parameters

    • redirectURL (type: string): The URL to redirect to after the password is reset
    • subject (type: string): The subject line for the password-reset email
    • RoutingOptions: An (object with routing-specific options)[/docs/Developer%20reference/Utils/routers.md#routingoptions-interface]
warning

The redirect URL must be in the Forio domain. Otherwise, an error is thrown.

Return value​

A Promise that resolves to void.

Usage example​

JavaScript example
import authAdapter from 'epicenter-libs';

document.getElementById('reset-password').addEventListener('submit', async(event) => {
    event.preventDefault();
    const { handle } = event.target.elements;
    await authAdapter.resetPassword(handle.value, 'https://forio.com/app/account/project',
                                    'Please reset your password!');
    }
);

Verify a security token​

The verify() function checks the validity of a token and returns a Promise resolving to the currently authenticated Session object.

Function signature
export async function verify(
                        token: string,
                        optionals: RoutingOptions = {},
                        ): Promise<Session>

Permissions​

Requires a role of ANONYMOUS or higher.

Parameters​

  • token (type: string): a Bearer token
  • RoutingOptions: an optional parameter containing an (object with routing-specific options)[/docs/Developer%20reference/Utils/routers.md#routingoptions-interface]

Report user's outcome​

To send the outcome of the user's participation in a simulation to an external link, use the ssoOutcome() function.

Function signature
export async function ssoOutcome(
                        ltiVersion : string,
                        outcomeInformation: {value: number, sourcedId: string, outcomeServiceUrl: string,},
                        optionals: RoutingOptions = {}
                    ): Promise<Record<string, unknown>>

Parameters​

  • ltiVersion: string (Required) - The version of LTI to use. Valid values: "1.1", "1.2", and "1.3".
  • outcomeInformation (Required) - An object containing the outcome details to be sent to the outcome service:
    • value: number - The value to pass back to the outcomeServiceUrl. For example, the grade a student received upon simulation completion.
    • sourcedId: string - The ID of the current assignment or student as provided by the client using the SSO service.
    • outcomeServiceUrl: string - The URL where the outcome information should be sent.
  • optionals: RoutingOptions (Optional) - An object containing additional routing options. Pass network call option overrides here. Defaults to an empty object {}.

Return value​

A promise that resolves to undefined (indicating success).